By the end of this worksheet you should be able to:
program your own experiments in jsPsych
host the experiment online using cognition.run
use the participant data for analysis
apply the basic skills you have learnt for your own
purposes
learn some extra skills such as HTML, javascript,
CSS and JSON
Pre-requisites
To complete the aims you will need to:
follow this worksheet
ask questions if you are not sure/be able to
google
have a working computer and internet
connection
be patient when things do not work
You do not need to:
have any programming knowledge
have high computer literacy
know anything about jsPsych, cognition.run, html, css or
javascript
be a linguist
Structure
The worksheet will go through the following sections:
Introducing cognition.run
creating an account
creating a new experiment
familiarisation with the interface
Introducing jsPsych
Introducing cognition.run and jsPsych
cognition.run
What is it?
A free and easy way to host your jsPsych experiments.
Why would I use it?
If you do not have access to your own server, or do not want to pay
for alternative online server options, this is a nice and simple
solution for researchers.
Do I have to spend lots of time learning how it
works?
Not really, once you learn how to use jsPsych the interface is really
good for beginners to navigate and use.
The free account will allow you to:
run your jsPsych experiments online
code and preview your experiment
access your data as a csv file
collect a maximum of 80 participants per experiment
learn the basics and complete this worksheet
It will not be suitable if you:
need to collect a large amount of data from lots of
participants
collect data that would not be usable in csv format (e.g. audio
recordings from participants)
have stimuli that are very large in size (>2 MB,
e.g. videos)
are looking to host your experiments on your own server
Register for a free account by filling in the
form.
You will then see a dashboard, where you can see your
experiments. Click on the + New task button to create a new
experiment.
Where it says task name type the name
demo (you can choose a different name if you want, but
this is the name that we will use). If you click on the
Show advanced configuration button to see additional
settings, which may be relevant depending on your ethics application
(e.g. data storage location, IP address logging). Click the
Save button to create the experiment.
Now you will see the experiment’s dashboard. There are several
options on this page which we will cover later, but for now we need to
click on the Source code button.
On this page you can start writing your code that makes your
experiment. Before we start writing our code we will need to know how
jsPsych works, which will be covered in the next section. We will return
to the cognition.run interface too and see how to interact with it in
more detail.
Things might look different
The screenshots above
might look different if you are reading this worksheet at a later date.
This is because websites change, especially ones that are constantly
developing, which also means the cost of using the service might also
change.
jsPsych
What is it? A free and open source library that
allows users to create and run experiments online. It relies on
javascript, a programming language that most websites use, to
implement plugins that can be used to make your
experiments.
de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating
behavioral experiments in a web browser. Behavior Research
Methods, 47(1), 1-12. doi:10.3758/s13428-014-0458-y.
Why should I use it? It is an extremely
adaptable and easy to use, with a growing community of users, support
and contributors, making it more accessible for everybody to conduct
research online. It is also free and open source.
Do I have to spend lots of time learning how to use
it? Probably. There is definitely a learning curve, which
will take time to get around, but you learn lots of skills along the
way. The more you learn, the more you can do. However, if you want to
learn the basics you do not need too long to get a working experiment
programmed and available to participants.
Should I be worried if I do not know what javascript
is? No. The great thing about jsPsych is that much of the
hard work is already done by others, which means you can get by without
worrying about the really complex stuff.
Versions of jsPsych
You might have noticed that
jsPsych has different versions, e.g. 7.3.1, 6.3.0. This is somewhat
confusing at first as you would hope that there would be no major
differences in which version you are using, or that you would just
choose the latest version. However, there are some important differences
between the versions that can affect whether your script will work.
These are largely based on whether you are using version 6.x.x or
7.x.x
Always
try to write somewhere in your script which version of jsPsych you are
working with.
Running experiments
In order to run your experiments, you have write code that will tell
jsPsych what you want it to do. This requires you to speak the same way
as jsPsych, so that your instructions can be interpreted properly.
Imagine you have to guide somebody from point A to point B on a map,
you will have to learn how to give basic instructions like turn
left, stop, continue, this is what your code will
have to do (but in the context of a linguistics experiment, so more like
show this stimuli, collect this input, measure the
time it takes to press this button).
Using cognition.run with jsPsych
To run your experiment, you will need somewhere to write your code.
We will therefore return to cognition.run.
The image below outlines which parts of the interface can be used for
different purposes. For now, we will focus on 1 and 2
of the interface (writing code and previewing how it looks), with 3 and
4 being explained in more detail later.
0. Commenting your code
Before you start writing proper code that does things, it is
important to remember that it is not just the computer who will
interpret you write… you and other human brains need to as well.
To make it easier for humans, you can add comments
to your code.
Comments don’t do anything to your actual code, but add information
to make it easier to understand and interpret. Imagine talking to
somebody in a language that you both know, but there is somebody else in
the group who does not speak that language, so you might offer a
simplified translation to that person, so that they know what is
happening. This is sort of similar to what comments do.
You can write a comment in the code section of the cognition.run
interface in the following way:
// This is a comment
These can be as long as you want, but must have // at
the start of each new line.
Let’s try writing a useful comment in our script, where we say:
the title of the experiment
what version of jsPsych we are using
when we wrote the code [today]
who is the author of the code [your name]
// --------// Title: My first experiment// jsPsych version: 7.3.1// date: [today]// author: [your name]//----------
1. Initiating jsPsych
Now we can start writing actual code that will allow us to use
jsPsych properly.
In order for your experiment to work, the first line of code in your
script should be:
var jsPsych =initJsPsych();
Notice that this is not a comment and has a specific structure, or
syntax, which is shown by the colour highlighting of the text.
We can deconstruct this to understand each part of the
code:
var this indicates that we want to create a
variable, which we can use in our experiment. Notice that
it is in a different colour to the rest of the text, this is because it
is a keyword that javascript understands to be important,
i.e. that you want to create a variable.
jsPsych this is the name of our variable, in theory
you can name variables anything that you want.
= this is an operator it is used to assign
a value to a variable, in this case whatever is on the right of the
equals sign will be assigned to our jsPsych variable.
initJsPsych() this is a function specifically made
for jsPsych experiments, it allows us to initiate an experiment, without
this function we would not be able to do anything. Think of it as
turning on the power button, nothing will happen until you have this
function stored as a variable.
; this is a semi-colon, it is an important part of
your code as it will allow the script to know that your specific bit of
code (or statement) is finished and you can move on to your next
one.
What is a variable?
See this
page for more information on what var means.
Choosing a name for your variable
When naming your
variable you should follow these rules:
never include spaces (use_underscores_instead)
never begin with a number
never use a special javascript name (e.g. ‘var’ is not a good name for
your variable)
always make them unique to other variables
always make them memorable
always be aware of upper and lower case (‘myVariable’ will be distinct
from ‘myvariable’)
What goes inside the
brackets?
When you see brackets for a function, there are
normally some additional parameters that you can set, to see what these
are you can always refer to the official jsPsych
documentation, for now we will keep our experiment to the default
settings, so we do not need to add anything inside the
brackets.
2. Timelines
For our experiment to work we need to add a timeline. We
use these to store each of the components of our
experiment, e.g. informed consent, instructions, practice trials,
experimental trials, ending message.
The timeline is simply the place where we store all of
the components, ensuring that they will be presented to the participant
in a specific order.
We would normally create a timeline before
making the components.
This can be done by creating a var called
timeline and then the thing that this variable will store
is an empty array, which is denoted by the
[].
Once we have set up the timeline, then we can make the components and
push them into the timeline array. So our timeline
would eventually look like [informed consent, instructions, practice
trials, experimental trials, ending message].
var timeline = [];
3. Experimental components and plugins
Now we can actually make a component to show to the participant.
Components can be almost anything you can think of, all you need to
do is convert your experimental idea into the suitable components. This
may take a bit more expertise for really complex experiments, but
luckily JsPsych has already done a lot of the work and has a toolbox
full of typical components that you would normally need to run an
experiment.
The documentation page is really nicely written and has examples of
each of the plugins, with sensible names so it should be relatively easy
to choose the plugin that suits your needs.
We will work through a few of these plugins to demonstrate how they
work.
html-button-response
var trial = {type: jsPsychHtmlButtonResponse,stimulus:'Ahoj světe',choices: ['click me!'],};
Important differences between cognition.run and normal jsPsych
experiments
Your experiment in cognition.run will look a
but different from other JsPsysch experiments, e.g. the ones you might
see that were hosted on private servers. This is because cognition.run
does some things automatically, so you do not need to worry about adding
specific code.
One of the main differences is that all of the
standard JsPsych plugins are automatically loaded for you. We will
discuss this later in the worksheet, but if you have used JsPsych
before, or are copying code from a non cognition.run experiment you
might need to be aware of this.
Essentially, the code you have
in your cognition.run experiment will all be javascript, whereas a
typical JsPsych experiment will be a html file, with the javascript
embedded within that file.
